home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3p / ussetlock.z / ussetlock
Encoding:
Text File  |  1998-10-20  |  10.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ussetlock, uscsetlock, uswsetlock, ustestlock, usunsetlock - spinlock
  10.      routines
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<uuuulllloooocccckkkkssss....hhhh>>>>
  14.  
  15.      iiiinnnntttt uuuusssssssseeeettttlllloooocccckkkk ((((uuuulllloooocccckkkk____tttt lllloooocccckkkk))));;;;
  16.  
  17.      iiiinnnntttt uuuussssccccsssseeeettttlllloooocccckkkk ((((uuuulllloooocccckkkk____tttt lllloooocccckkkk,,,, uuuunnnnssssiiiiggggnnnneeeedddd ssssppppiiiinnnnssss))));;;;
  18.  
  19.      iiiinnnntttt uuuusssswwwwsssseeeettttlllloooocccckkkk ((((uuuulllloooocccckkkk____tttt lllloooocccckkkk,,,, uuuunnnnssssiiiiggggnnnneeeedddd ssssppppiiiinnnnssss))));;;;
  20.  
  21.      iiiinnnntttt uuuusssstttteeeessssttttlllloooocccckkkk ((((uuuulllloooocccckkkk____tttt lllloooocccckkkk))));;;;
  22.  
  23.      iiiinnnntttt uuuussssuuuunnnnsssseeeettttlllloooocccckkkk ((((uuuulllloooocccckkkk____tttt lllloooocccckkkk))));;;;
  24.  
  25. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  26.      This set of routines provide a standard test and set facility.  If the
  27.      lock is free then it is atomically locked, and control is returned to the
  28.      caller.  If the lock is already locked, the caller either spins waiting
  29.      for the lock or gets queued.  The locks are based in user address space
  30.      thus avoiding any system call overhead in the case where the lock is
  31.      available.
  32.  
  33.      The actual algorithm used to implement these functions depends on whether
  34.      the system is a multiprocessor or a single processor.  In the
  35.      multiprocessor case, if the lock is already locked, the caller will spin
  36.      (i.e. busy wait).  The amount of time it spins depends on the function -
  37.      for _uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk, a system chosen value is used, for _uuuu_ssss_cccc_ssss_eeee_tttt_llll_oooo_cccc_kkkk and
  38.      _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk the value of _s_p_i_n_s is used.  If, after _s_p_i_n_s attempts to
  39.      acquire the lock have all failed, the function will either return
  40.      (_uuuu_ssss_cccc_ssss_eeee_tttt_llll_oooo_cccc_kkkk) or yield the processor (_uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk, or _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk).  The
  41.      yield is affected by calling _ssss_gggg_iiii_nnnn_aaaa_pppp(2).  After returning from yield,
  42.      _uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk and _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk will again attempt to acquire the lock _s_p_i_n_s
  43.      times.  This will continue until the lock is finally acquired.  Note that
  44.      if a process spends much of its time waiting for a lock without giving up
  45.      the processor, then the total throughput of the system may be reduced.
  46.      On the other hand, by giving up the processor too quickly, there is a
  47.      longer latency between when the lock is freed and the caller obtains the
  48.      lock.
  49.  
  50.      The implementation of locks on single processor systems never spin; if
  51.      the lock is unavailable the caller is atomically queued.  This queueing
  52.      operation suspends the calling process and forces a scheduling cycle.
  53.      Processes are removed from the queue in FIFO order when the lock is
  54.      released.
  55.  
  56.      The appropriate lock algorithm is selected automatically at program
  57.      startup time.  Different levels of debugging information can be requested
  58.      via uuuussssccccoooonnnnffffiiiigggg(3P).
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  71.  
  72.  
  73.  
  74.      uuuusssssssseeeettttlllloooocccckkkk doesn't return until the lock specified by _l_o_c_k is acquired.
  75.      uuuussssccccsssseeeettttlllloooocccckkkk attempts to acquire a lock _s_p_i_n_s times, returning a 1 if the
  76.      lock was acquired, and a 0 if it was not available.  uuuusssswwwwsssseeeettttlllloooocccckkkk is
  77.      similar to uuuusssssssseeeettttlllloooocccckkkk,,,, except that the caller specifies the number of
  78.      times the lock is attempted to be acquired before the process gives up
  79.      control of the processor.  On a single processor this call is identical
  80.      with uuuusssssssseeeettttlllloooocccckkkk.  uuuusssstttteeeessssttttlllloooocccckkkk returns the instantaneous value of the lock,
  81.      a 0 if it is not locked, and a 1 if it is locked.  uuuussssuuuunnnnsssseeeettttlllloooocccckkkk releases
  82.      the lock.
  83.  
  84.      When invoked with a valid lock, uuuusssssssseeeettttlllloooocccckkkk and uuuusssswwwwsssseeeettttlllloooocccckkkk do not return
  85.      until the lock is acquired.  An invalid lock will yield unpredictable
  86.      results.
  87.  
  88.      It is allowed to call uuuussssuuuunnnnsssseeeettttlllloooocccckkkk on a lock that is either not locked or
  89.      locked by another process.  In either case, the lock will be unlocked.
  90.      Double tripping, i.e. calling a set lock function twice with the same
  91.      lock is also permissible.  The caller will block until another process
  92.      unsets the lock.
  93.  
  94.      In order to use a lock, the caller must have joined the shared arena out
  95.      of which the lock is allocated (via uuuussssiiiinnnniiiitttt(3P)), and have a file
  96.      descriptor to a uuuusssseeeemmmmaaaa(7M) device to suspend/unsuspend on.  As a
  97.      convenience, these routines will automatically do this for members of a
  98.      share group, or for related (via ffffoooorrrrkkkk(2)) processes.  This automatic
  99.      facility can generate the same errors as uuuussssiiiinnnniiiitttt(3P).  These errors will
  100.      be passed back to the caller.  If tracing is enabled (see uuuussssiiiinnnniiiitttt(3P))
  101.      then any errors will cause a message to be printed to _s_t_d_e_r_r.  To avoid
  102.      these errors and therefore not need to check for errors on every lock
  103.      call, have each process call uuuussssiiiinnnniiiitttt(3P) before using any locks.
  104.  
  105.      These locks are designed to be fast in the case where the lock is
  106.      available.  On a Challenge R4400 multiprocessor a uuuusssssssseeeettttlllloooocccckkkk, uuuunnnnsssseeeettttlllloooocccckkkk
  107.      pair takes about 500nS.
  108.  
  109.      When using debugging lock types the following debugging prints can occur.
  110.  
  111.      _D_o_u_b_l_e _t_r_i_p_p_e_d _o_n _l_o_c_k @ _0_x... _b_y _p_i_d ... will be printed when an attempt
  112.      is made to acquire a lock that is already held by the caller.
  113.  
  114.      _U_n_l_o_c_k_i_n_g _l_o_c_k _t_h_a_t _o_t_h_e_r _p_r_o_c_e_s_s _l_o_c_k_d _l_o_c_k @ _0_x... _b_y _p_i_d ... will be
  115.      printed when an attempt is made to release a lock that is not held by the
  116.      process attempting to release it.
  117.  
  118.      _U_n_s_e_t _l_o_c_k, _b_u_t _l_o_c_k _n_o_t _l_o_c_k_e_d. _l_o_c_k @ _0_x... _p_i_d ... will be printed
  119.      when using debug software locks, and an attempt was made to unlock a lock
  120.      that was not locked.
  121.  
  122.      The following errors can occur due to misuse of a lock:
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  137.  
  138.  
  139.  
  140.      [EBADF]        The underlying file descriptor for the lock was closed or
  141.                     re-used by the application.
  142.  
  143. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  144.      sginap(2), barrier(3P), uscas(3P), usconfig(3P), usctllock(3P),
  145.      usdumplock(3P), usfreelock(3P), usinitlock(3P), usinit(3P), uspsema(3P).
  146.      usnewlock(3P), usnewsema(3P), usema(7M).
  147.  
  148. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  149.      uuuusssssssseeeettttlllloooocccckkkk,,,, uuuusssswwwwsssseeeettttlllloooocccckkkk,,,, uuuussssccccsssseeeettttlllloooocccckkkk,,,, and uuuusssstttteeeessssttttlllloooocccckkkk will return a 1 if the
  150.      lock is acquired and a 0 if the lock is not acquired.  uuuussssuuuunnnnsssseeeettttlllloooocccckkkk always
  151.      returns 0 if successful.  On error, -1 is returned and _e_r_r_n_o is set to
  152.      indicate the error.
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.